<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
  File: README
  
    &mdash; WePay Signer for Ruby
  
</title>

  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />

  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  pathId = "README";
  relpath = '';
</script>


  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>


  </head>
  <body>
    <div class="nav_wrap">
      <iframe id="nav" src="file_list.html"></iframe>
      <div id="resizer"></div>
    </div>

    <div id="main" tabindex="-1">
      <div id="header">
        <div id="menu">
  
    <a href="_index.html">Index</a> &raquo; 
    <span class="title">File: README</span>
  
</div>

        <div id="search">
  
    <a class="full_list_link" id="class_list_link"
        href="class_list.html">

        <svg width="24" height="24">
          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
        </svg>
    </a>
  
</div>
        <div class="clear"></div>
      </div>

      <iframe id="search_frame" src="file_list.html"></iframe>

      <div id="content"><div id='filecontents'><h1>WePay Signer for Ruby</h1>

<p><a href="https://github.com/wepay/signer-ruby"><img src="http://img.shields.io/badge/source-wepay/signer%E2%80%93ruby-blue.svg?style=flat-square" alt="Source" /></a>
<a href="https://rubygems.org/gems/wepay-signer"><img src="https://img.shields.io/gem/v/wepay-signer.svg?style=flat-square" alt="Latest Stable Version" /></a>
<a href="https://rubygems.org/gems/wepay-signer"><img src="https://img.shields.io/gem/dt/wepay-signer.svg?style=flat-square" alt="Total Downloads" /></a>
<a href="https://github.com/wepay/signer-ruby/issues"><img src="http://img.shields.io/github/issues/wepay/signer-ruby.svg?style=flat-square" alt="Open Issues" /></a>
<a href="https://travis-ci.org/wepay/signer-ruby"><img src="http://img.shields.io/travis/wepay/signer-ruby/master.svg?style=flat-square" alt="Build Status" /></a>
<a href="https://coveralls.io/r/wepay/signer-ruby?branch=master"><img src="http://img.shields.io/coveralls/wepay/signer-ruby/master.svg?style=flat-square" alt="Coverage Status" /></a>
<a href="https://codeclimate.com/github/wepay/signer-ruby"><img src="http://img.shields.io/codeclimate/github/wepay/signer-ruby.svg?style=flat-square" alt="Code Climate" /></a>
<a href="https://scrutinizer-ci.com/g/wepay/signer-ruby"><img src="http://img.shields.io/scrutinizer/g/wepay/signer-ruby.svg?style=flat-square" alt="Code Quality" /></a>
<a href="https://github.com/biplap-sarkar"><img src="http://img.shields.io/badge/author-@biplap%E2%80%93sarkar-blue.svg?style=flat-square" alt="Author" /></a>
<a href="https://github.com/skyzyx"><img src="http://img.shields.io/badge/author-@skyzyx-blue.svg?style=flat-square" alt="Author" /></a></p>

<p>The <strong>Signer</strong> class is designed for those who are signing data on behalf of a public-private keypair.</p>

<p>In principle, the "client party" has public key (i.e., <code>client_id</code>) and a matching private key (i.e., <code>client_secret</code>) that can be verified by both the signer and the client (but nobody else as we don't want to make forgeries possible).</p>

<p>The "signing party" has a simple identifier which acts as an additional piece of entropy in the algorithm, and can help differentiate between multiple signing parties if the client party does something like try to use the same public-private keypair independently of a signing party (as is common with GPG signing).</p>

<p>Based on a simplified version of the AWS Signature v4.</p>

<p>This project uses <a href="http://semver.org">Semantic Versioning</a> for managing backwards-compatibility.</p>

<blockquote><p><strong>NOTE:</strong> To use this gem alongside the <code>wepay</code> gem, the <code>wepay</code> gem MUST be at least version <code>0.2.0</code>.</p></blockquote>

<ul>
<li><a href="https://wepay.github.io/signer-ruby/">API Reference</a></li>
</ul>


<h2>Examples</h2>

<p>(Using <a href="https://gist.github.com/js-coder/3581285">word_wrap()</a> for line wrapping.)</p>

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client_id'>client_id</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>your_client_id</span><span class='tstring_end'>&#39;</span></span>
<span class='id identifier rubyid_client_secret'>client_secret</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>your_client_secret</span><span class='tstring_end'>&#39;</span></span>

<span class='id identifier rubyid_signer'>signer</span> <span class='op'>=</span> <span class='const'>WePay</span><span class='op'>::</span><span class='const'>Signer</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_client_id'>client_id</span><span class='comma'>,</span> <span class='id identifier rubyid_client_secret'>client_secret</span><span class='rparen'>)</span>
<span class='id identifier rubyid_signature'>signature</span> <span class='op'>=</span> <span class='id identifier rubyid_signer'>signer</span><span class='period'>.</span><span class='id identifier rubyid_sign'>sign</span><span class='lparen'>(</span><span class='lbrace'>{</span>
  <span class='symbol'>:token</span>        <span class='op'>=&gt;</span> <span class='id identifier rubyid_your_token'>your_token</span><span class='comma'>,</span>
  <span class='symbol'>:page</span>         <span class='op'>=&gt;</span> <span class='id identifier rubyid_wepay_page_to_visit'>wepay_page_to_visit</span><span class='comma'>,</span>
  <span class='symbol'>:redirect_uri</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_partner_page_to_return_to'>partner_page_to_return_to</span><span class='comma'>,</span>
<span class='rbrace'>}</span><span class='rparen'>)</span>

<span class='id identifier rubyid_puts'>puts</span> <span class='id identifier rubyid_signature'>signature</span><span class='period'>.</span><span class='id identifier rubyid_word_wrap'>word_wrap</span><span class='lparen'>(</span><span class='int'>64</span><span class='rparen'>)</span>
<span class='comment'>#=&gt; dfbffab5b6f7156402da8147886bba3eba67bd5baf2e780ba9d39e8437db7c47
</span><span class='comment'>#=&gt; 35e9a0b834aa21ac76f98da8c52a2a0cd1b0192d0f0df5c98e3848b1b2e1a037
</span>
<span class='id identifier rubyid_querystring'>querystring</span> <span class='op'>=</span> <span class='id identifier rubyid_signer'>signer</span><span class='period'>.</span><span class='id identifier rubyid_generate_query_string_params'>generate_query_string_params</span><span class='lparen'>(</span><span class='lbrace'>{</span>
  <span class='symbol'>:token</span>        <span class='op'>=&gt;</span> <span class='id identifier rubyid_your_token'>your_token</span><span class='comma'>,</span>
  <span class='symbol'>:page</span>         <span class='op'>=&gt;</span> <span class='id identifier rubyid_wepay_page_to_visit'>wepay_page_to_visit</span><span class='comma'>,</span>
  <span class='symbol'>:redirect_uri</span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_partner_page_to_return_to'>partner_page_to_return_to</span><span class='comma'>,</span>
<span class='rbrace'>}</span><span class='rparen'>)</span>

<span class='comment'>#=&gt; client_id=your_client_id&amp;
</span><span class='comment'>#=&gt; page=https://wepay.com/account/12345&amp;
</span><span class='comment'>#=&gt; redirect_uri=https://partnersite.com/home&amp;
</span><span class='comment'>#=&gt; token=dfbffab5b6f7156402da8147886bba3eba67bd5baf2e780ba9d39e8437db7c47...
</span></code></pre>

<h2>Installation</h2>

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>wepay-signer</span><span class='tstring_end'>&#39;</span></span>
</code></pre>

<p>And include it in your scripts:</p>

<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>&#39;</span><span class='tstring_content'>wepay-signer</span><span class='tstring_end'>&#39;</span></span>
</code></pre>

<h2>Testing</h2>

<p>Firstly, run <code>bundle install</code> to download and install the dependencies.</p>

<p>You can run the tests as follows:</p>

<pre class="code bash"><code class="bash">make test
</code></pre>

<h2>API Reference</h2>

<p>The API Reference is generated by a tool called <a href="http://yardoc.org">YARD</a>. Once it's installed, you can generate
updated documentation by running the following command in the root of the repository.</p>

<pre class="code bash"><code class="bash">make docs
</code></pre>

<h2>Deploying</h2>

<ol>
<li>The <code>Makefile</code> (yes, <code>Makefile</code>) has a series of commands to simplify the development and deployment process.</li>
<li>Also install <a href="https://github.com/mtdowling/chag">Chag</a>. This is used for managing the CHANGELOG and annotating the Git release correctly.</li>
</ol>


<h3>Updating the CHANGELOG</h3>

<p>Make sure that the CHANGELOG.md is human-friendly. See <a href="http://keepachangelog.com">http://keepachangelog.com</a> if you don’t know how.</p>

<h3><code>make</code></h3>

<p>Running <code>make</code> by itself will show you a list of available sub-commands.</p>

<pre class="code bash"><code class="bash">$ make
all
docs
gem
install
pushdocs
pushgem
tag
test
version
</code></pre>

<h3><code>make pushdocs</code></h3>

<p>You will need to have write-access to the <code>wepay/signer-ruby</code> repository on GitHub. You should have already set up:</p>

<ul>
<li>Your SSH key with your GitHub account.</li>
<li>Had your GitHub user given write-access to the repository.</li>
</ul>


<p>Then you can run:</p>

<pre class="code bash"><code class="bash">make pushdocs
</code></pre>

<p>You can view your changes at <a href="https://wepay.github.io/signer-ruby/">https://wepay.github.io/signer-ruby/</a>.</p>

<h3><code>make pushgem</code></h3>

<p>You will need to have pulled-down the proper gem credentials first. When prompted, enter your
<a href="http://rubygems.org">RubyGems</a> password.</p>

<p>Login and view your <a href="https://rubygems.org/profile/edit">RubyGems profile page</a> to see the proper command.</p>

<p>Then you can run:</p>

<pre class="code bash"><code class="bash">make pushgem
</code></pre>

<p>If you need to <a href="https://stackoverflow.com/questions/8487218/how-to-add-more-owners-to-a-gem-in-rubygem">add an additional gem owner</a>:</p>

<pre class="code bash"><code class="bash">gem owner wepay -a api@wepay.com
</code></pre>

<p>You can view your changes at <a href="https://rubygems.org/gems/wepay-signer">https://rubygems.org/gems/wepay-signer</a>.</p>

<h3><code>make tag</code></h3>

<p>This will leverage Chag to generate a commit for the tag. Then you can run:</p>

<pre class="code bash"><code class="bash">make tag
</code></pre>

<h3>Drafting a GitHub release</h3>

<ol>
<li>Go to <a href="https://github.com/wepay/signer-ruby/tags">https://github.com/wepay/signer-ruby/tags</a></li>
<li>Find the new tag that you just pushed. Click the ellipsis (<code>…</code>) to see the commit notes. Copy these.</li>
<li>To the right, choose <em>Add release notes</em>. Your <em>Tag version</em> should be pre-filled.</li>
<li>The <em>Release title</em> should match your <em>Tag version</em>.</li>
<li>Inside <em>Describe this release</em>, paste the notes that you copied on the previous page.</li>
<li>Choose <em>Publish release</em>.</li>
<li>Your release should now be the latest. <a href="https://github.com/wepay/signer-ruby/releases/latest">https://github.com/wepay/signer-ruby/releases/latest</a></li>
</ol>


<h2>Contributing</h2>

<p>Here's the process for contributing:</p>

<ol>
<li>Fork Signer to your GitHub account.</li>
<li>Clone your GitHub copy of the repository into your local workspace.</li>
<li>Write code, fix bugs, and add tests with 100% code coverage.</li>
<li>Commit your changes to your local workspace and push them up to your GitHub copy.</li>
<li>You submit a GitHub pull request with a description of what the change is.</li>
<li>The contribution is reviewed. Maybe there will be some banter back-and-forth in the comments.</li>
<li>If all goes well, your pull request will be accepted and your changes are merged in.</li>
</ol>


<h2>Authors, Copyright &amp; Licensing</h2>

<ul>
<li>Copyright (c) 2015-2016 <a href="http://wepay.com">WePay</a></li>
</ul>


<p>See also the list of <a href="https://github.com/wepay/signer-ruby/graphs/contributors">contributors</a> who participated in this project.</p>

<p>Licensed for use under the terms of the <a href="http://opensource.org/licenses/Apache-2.0">Apache 2.0</a> license.</p>
</div></div>

      <div id="footer">
  Generated on Fri Aug 12 11:10:12 2016 by
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.8.7.6 (ruby-2.3.1).
</div>

    </div>
  </body>
</html>